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1. Introductica. 


This document describes the latest changes made to the archive file format used on the UNIX* 
operating system. This archive format was introduced to the 

VAX+-11/780 and 11/750 versions of the UNIX operating system as of System V. 
This document addresses only the archive formats on these processors. 


The archive command ar is used to combine several files into one file. No restriction is placed on 
the contents of the individual files. Archives are used mainly as libraries to be searched by the link 
editor during the compilation process. This new archive format allows the link editor to search 
libraries more efficiently due to an initia] symbol directory that acts like a table of contents for all 
members of the archive. Figure 1 shows the overall structure. 
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Figure 1. Archive File Format 
The following sections of this document discuss each portion of the above format in some detail. 


2. Archive Header 


The archive header allow the link editor to identify this file as being an archive. Each archive 
begins with such a header which is made up of the components listed in table 1. 


* UNIX is a trademark of Bell Telephone Laboratories, Inc. 
+ VAX and PDP are trademarks of Digital Equipment Corporation. 
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Bytes Declaration 
00-03 ar magic Magic number 


04-19 ar_name Name of archive 
20-23 ar_ date Date of last modification 
24-27 char arsyms |§ Number of symbol entries 


TABLE 1. Archive Header Format 


The archive magic number is defined to be the string <ar>. The ar_date field indicates the last 
time a change occurred anywhere in the archive, such as modifying a member, adding a member or 
deleting a member. The number of symbol entries in the table of contents will be zero if the archive 
does not contain object modules, that is, it is not being used as a library. 


2.1 C Data Strectare 
The C data structure used for the archive header is as follows: 


#define ARMAG *<ar>" 
#define SARMAG 4 


struct ar_hdr { /* archive header °/ 
char ar_magic[SARMAG]; /* magic number */ 
char ar_name[16]; /* archive name */ 
char ar_date[4); /* date of last modification */ 
char ar_syms/4]; /* number of ar_sym entries */ 
3. Symbol Directory 


Each archive which contains members that are in Common Object File format (see UNIX system 
Reference manual a.out(4)) includes an archive symbol directory. This directory is created from 
the individual file member symbo] tables. It is used by the UNIX link editor to determine which 
archive members must be loaded during the link edit process. Previously, the link editor would need 
to make one complete pass over the library reading each member to see if it needed to be loaded. 
The use of a symbol directory allows the link editor to perform random access on the library so it 
needs only to read the member entries that must be loaded. 


The symbol directory immediately follows the archive header described above. The number of 
symbol directory entries is indicated in the archive header a7_syms variable. Each symbol directory 
entry has the format found in table 2. 


Bytes Declaration Name Description 
00-07 char sym_name Symbol name used by link editor 


08-11 char sym_ptr Location of symbol in archive 


TABLE 2. Symbol Directory Format 


The archive symbol directory is automatically created and/or updated by the UNIX system ar 
command. 


3.1 C Data Sorectare 
The C structure format used for a symbol entry is: 


struct ar_sym { /* archive symbol table entry */ 
char sym_namel8); /* symbol name, recognized by Id */ 
char sym_ptrl4); /* archive position of symbol */ 


4. Member Header 


Following the archive header and symbol directory are the archive file members. Each file member 
consists of a file member header followed by the file member contents. The format of the file 
member header is given in Table 3. 


Bytes Declaration 


Name of file member 
Member last modification date 


Member user identification 
Member group identification 
Member mode 

Size of file member in bytes 


TABLE 3. Member Header Format 


The user and group identification values and the mode value are the corresponding UNIX file 
system values for each member file. 


Note that there is no provision for leaving empty areas within an archive. 
4.1 C Dat Strecture 
The C structure used for file member headers is: 


struct arf_hdr { /* archive file member header */ 
char  arf_namel16); /* member name */ 
char arf_date[4); /* member date */ 
char arf_uid[4); /* member user identification */ 
char arf_gid[4),; /* member group identification */ 
char = arf_model 4); /* member mode */ 

char arf_size[4); /* member size */ 


8. Genera! Details 
_ $1 Portability 


All information in the archive header, symbol directory and file member headers is stored in a 
portable format. All character data (e.g. archive/file member names) is inherently machine 
independent. All numeric data contained in the headers is stored as a four byte quantity. Special 
conversion routines exist for accessing this information. These routines are available in the UNIX 


system Jibld.a library and a description of them can be found in the UNIX Reference manual page 
sputl (3X). 


5.2 Transportability 


Common format archives can be moved between UNIX systems as long as the portable archive 
command ar (1) is used. Conversion tools exist allowing archives created on UNIX systems not 
supporting this format to be converted into this format. A straightforward approach is simply to 
re-archive the files using the portable archive command. If this is not possible then the UNIX 
system command convert(1) can be used to convert pre-System V VAX archives into this 
format. Also, the UNIX system command arcv exists for the conversion of PDP-11/70 archives into 
this format. See Section 1 of the UNIX Reference manual for the exact usage of these commands. 


$3 Efficiency 


For accessing and efficiency reasons each archive file member is forced to begin on a word boundary. 
To accomplish this null bytes may be inserted between files if necessary. However, the size of the 
member given in the file member header reflects the actual size of the file exclusive of padding. 


